/*
 * @(#)TimeConversion.java 1.0 2008/12/07
 */
package stardust.core.support.conversion;


import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Locale;


/**
 * <code>TimeConversion</code> 类可将格式已知的字符串转化为时间对象。
 * <p/>
 * @see StringConversion
 * @version 1.0, 2008/12/07
 * @author ChenChang
 */
public class TimeConversion
{

  /**
   * 将已知格式的字符串转换为时间对象，返回转换后的时间对象，失败抛出 {@link ParseException}，匹配模式参考下列说明：
   * <p>
   * <b>重复模式字符以使转换字符不足时补零。</b><br />
   * y 年<br />
   * M 年中的月份；<br />
   * d 月份中的天数；<br />
   * G Era标志符；<br />
   * w 年中的周数；<br />
   * W 月份中的周数；<br />
   * D 年中的天数；<br />
   * F 月份中的星期；<br />
   * E 星期中的天数；<br />
   * a Am/pm标记；<br />
   * H 一天中的小时数（0-23）；<br />
   * k 一天中的小时数（1-24）；<br />
   * K am/pm中的小时数（0-11）；<br />
   * h am/pm中的小时数（1-12）；<br />
   * m 小时中的分钟数（0～59）；<br />
   * s 分钟中的秒数（0～59）；<br />
   * S 毫秒数（0～999）；<br />
   * z 时区General time zone Pacific Standard Time; PST; GMT-08:00；<br />
   * Z 时区RFC 822 time zone -0800；<br />
   * MMM 月份的字符串表示；<br />
   * EEE 星期的字符串表示。<br />
   * </p>
   * <p/>
   * @param date
   * 一个需要转换的字符串对象。
   * @param pattern
* 匹配格式的表达式，参考匹配模式说明。
   * @param locale
 * 转换参数所面向的国家地区环境，这个参数为转换提供国际化支持，如果想采用系统默认值参考
   *          {@link #parseTime(String, String)} 方法或者通过
   *          {@link java.util.Locale#getDefault()} 方法直接取得系统默认值。
   * <p/>
   * @return 一个存储日期转换的结果的 {@link Date} 对象。
   * <p/>
   * @throws 转换失败抛出
* {@link ParseException} 异常。
   * @see #parseTime(String, String)
   */
  public static Date parseTime(String date, String pattern, Locale locale) throws ParseException
  {
    DateFormat dateFormat = new SimpleDateFormat(pattern, locale);

    return dateFormat.parse(date);
  }

  /**
   * 将已知格式的字符串转换为时间对象，返回转换后的时间对象，失败抛出 {@link ParseException}。<br />
   * 此方法不对国家地区进行硬性控制使用系统默认值。<br />
   * 如果想对转换结果进行区域控制或了解相关匹配模式需参考{@link #parseTime(String, String, Locale)}方法。
   * <p/>
   * @param date
   * 一个需要转换的字符串对象。
   * @param pattern
* 匹配格式的表达式，参考匹配模式说明。
   * <p/>
   * @return 一个存储转换的结果的 {@link Date} 对象。
   * <p/>
   * @throws 转换失败抛出
* {@link ParseException} 异常。
   * @see #parseTime(String, String)
   */
  public static Date parseTime(String date, String pattern) throws ParseException
  {
    return TimeConversion.parseTime(date, pattern, Locale.getDefault());
  }

}
